Skip to main content

📄 Document Structure

When adding Markdown documents to the internal-operations repository, please keep the following recommended and optional structures in mind. All .md and .mdx files must be stored within the /docs folder.

Required​

Following the structures are necessary for documents to interface well with Docusaurus.

frontMatter.title​

At a minimum, always include the title key in your Front Matter. This ensures a consistent sidebar label and can serve as the document’s primary header (H1). While Docusaurus can fallback to using the file name or the first heading it finds, defining an explicit title ensures a uniform and predictable experience across all documentation.

frontMatter.title
---
title: About
---

# {frontMatter.title}

Start of content here.

Folders​

When creating a new folder or sub-folder within the /docs directory, always include a README.md file to serve as the folder's index page. See the Folders section of the Sidebar document for more details.

Following the recommended structures ensures that documents remain uniform across the repository.

Headings​

Maintain a logical document structure by using a hierarchical heading sequence. Headings should cascade starting from H1 (the title), followed by H2 for main sections, H3 for subsections, and so on, without skipping levels.

Heading
---
title: About
---

# {frontMatter.title}

Document description

## My first section

Document section

### A sub section

Sub section to the above section

## My second section

Optional​

Consider these optional but highly recommended features to enhance your document's readability.

Front Matter​

While the title key is essential, leveraging additional Front Matter metadata significantly enhances your document’s integration with the site’s navigation and search. The keys highlighted below are the most commonly used; however, Docusaurus supports a vast range of options that you can explore as your needs evolve.

frontMatter.title
---
title: About
sidebar_position: 4
slug: about
---

# {frontMatter.title}

Start of content here.

In Docusaurus, the sidebar_position front matter key is used to control the order of documents within an autogenerated sidebar.

By default, Docusaurus sorts files and folders alphabetically. Using sidebar_position allows you to override this and explicitly place pages exactly where you want them.

Points to consider:

  1. Numerical Sorting: You assign a number to the key. Documents are then sorted in ascending order (lower numbers appear at the top).

  2. Floating Points: It supports decimals (e.g., 1.5), which is handy if you want to squeeze a new page between 1 and 2 without renumbering everything.

  3. Scope: It only affects the folder (sidebar slice) the file is currently in.

toc_max_heading_level​

By default, the Table of Contents (TOC) displays headings up to level 3 (H3). To show deeper heading levels for a specific page, use the toc_max_heading_level front matter key to set your desired depth on a per document basis. The following example will extend the TOC to 5 levels deep.

---
title: My Doc
slug: my_doc
toc_max_heading_level: 5
---

description​

A short description about a markdown file used by the <DocCardList /> component shown on every README.md file. If a description is not added to frontMatter then the first paragraph of the markdown is used.

slug​

In Docusaurus, the slug front matter key allows you to manually define a path of a document's URL, overriding the default path generated from the file system. Normally, a file located at /docs/guides/hello-world.md would result in the URL /guides/hello-world.

By using slug: hello, you decouple the web address from the physical file path. Even if the file is renamed to bonjour.md, the URL remains /guides/hello. This ensures that external links and bookmarks stay functional regardless of internal file reorganizations.

---
title: Hello World
sidebar_position: 4
slug: hello
---

Global vrs local slugs​

Beware of global slugs

A slug that is prefixed with a forward slash such as /mypage is global.

The slug slug: mypage is relative to its parent folder. This identifier must be unique within that specific folder to avoid conflicts.

In contrast, the slug slug: /mypage is global. If multiple documents share the same global slug, a conflict will occur. Global slugs bypass the standard folder-based URL structure; for example, http://localhost:3000/mypage will link directly to the document, regardless of how deeply it is nested within the /docs folder.

Categories (folders)​

Currently, this Docusaurus site does not utilize slugs for sidebar categories (folders). If you rename a folder perform a global search and replace any internal links that reference the old folder name.

Tabs​

See Tabs in the Extendable Features document.

Powered by MDX, Docusaurus allows you to embed interactive Tabs directly within your Markdown. This is ideal for displaying content like multi-language code snippets or platform-specific instructions. You can find implementation details in the Tabs section of our Extendable Features document.

This is an apple 🍎

Owner: Warren
Last updated on by Warren Anderson